Skip to content

feat(auth): add gog auth rekey to rotate the file keyring password - #1224

Merged
steipete merged 4 commits into
openclaw:mainfrom
sorenisanerd:feat/auth-keyring-rekey
Oct 20, 2026
Merged

steipete merged 4 commits into
openclaw:mainfrom
sorenisanerd:feat/auth-keyring-rekey

Conversation

@sorenisanerd

@sorenisanerd sorenisanerd commented Oct 17, 2026 •

Copy link
Copy Markdown
Contributor

Adds gog auth rekey <outdir> to rotate the file-keyring password by writing a separately verified encrypted copy. The command never installs that copy or changes live credential files; it prints installation instructions that retain the old keyring. Passwords come from environment variables or a no-echo terminal prompt, never argv or output.

The maintainer review found and fixed two data-safety defects before landing: source reads bypassed the store lock, and --force removed existing output before the replacement was written and verified. Rekey now holds the shared store lock through publication, stages the complete replacement beside the destination, independently verifies data and metadata, flushes ciphertext and directory metadata, and atomically exchanges directories on Linux/macOS. Publication sync failures roll back; a second failure preserves and identifies recovery paths. Decrypted byte buffers are cleared where practical, and legacy and encoded keyring formats remain readable.

Windows and filesystems without atomic directory exchange require a fresh output path; existing output is refused unchanged. Windows flushes ciphertext and publishes with a write-through rename. The normal .lock bookkeeping file may be created. Stop other gog processes before manually installing the snapshot, since credentials can change after rekey releases the lock.

Peter explicitly accepted this PR for landing on 2026-10-20. The secrets implementation received an in-session review and was excluded from external review under Peter's exception for this PR only. The CLI/documentation changes passed isolated Codex review at P0–P2. Original implementation and extensive compatibility coverage by @sorenisanerd; the Unreleased changelog thanks the contributor.

Validation: full make ci passed on an isolated Linux runner; focused rekey/CLI tests and secrets race tests passed. govulncheck ./... found no reachable vulnerability; GO-2026-5932 affects the unimported OpenPGP package only. All exact-head GitHub CI checks passed: run 39474735303.

@clawsweeper

clawsweeper Bot commented Oct 17, 2026 •

Copy link
Copy Markdown
Contributor

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

ClawSweeper review complete

ClawSweeper finished reviewing this revision. The review result is being finalized.

View the workflow run.

@clawsweeper clawsweeper Bot added clawsweeper:intake:feature Preliminary submission classification; full source review pending. P2 Normal priority bug or improvement with limited blast radius. rating: 🦐 gold shrimp Decent PR readiness signal, but merge confidence is limited. status: 📣 needs proof The PR needs real behavior proof before ClawSweeper can clear the contributor ask. and removed clawsweeper:intake:feature Preliminary submission classification; full source review pending. labels Oct 17, 2026
@clawsweeper

clawsweeper Bot commented Oct 17, 2026 •

Copy link
Copy Markdown
Contributor

Codex review: blocked before merge.

What this changes

Adds gog auth rekey &lt;outdir> to write and verify a separately encrypted copy of the file keyring.

Example: Rotate six stored credential entries with gog auth rekey /tmp/new-keyring.

  • Before: There is no supported command to rotate the whole file keyring password.
  • After: The command verifies six entries encrypted with the new password and prints installation instructions that retain the original directory.

Review scores

Measure Result What it means
Overall readiness 🦐 gold shrimp (3/6) The updated shipped-CLI evidence clears the earlier proof gap, and no actionable code finding remains; unresolved product and storage-contract approval caps overall readiness.
Proof confidence 🦞 diamond lobster (5/6) Sufficient (terminal): The supplied real CLI transcript exercises rotation of a v0.45.0-created keyring under isolated GOG_HOME, installation, preserved account metadata, successful Google calls, old-password rejection, retained-copy rollback, and unchanged original-keyring digests.
Patch quality 🐚 platinum hermit (4/6) No actionable review findings were identified.

Product

Kind: Feature · Worth it: Needs a maintainer decision · Fix scope: Complete
User problem: File-keyring users lack a supported way to rotate the encryption password for all stored credentials.
Reason: The feature has demonstrated practical value, but adds a command, flag, and environment variable while departing from the documented keyring coordination contract without owner approval.

Merge readiness

⛔ Blocked before merge - 1 item remains

Keep open: this PR supplies a useful capability absent from main. The earlier changelog finding is fixed and compatibility proof is sufficient; the remaining blocker is owner agreement on the command and its concurrency contract.

Priority: P2
Reviewed head: 0d18ccb2de8b42cb94f595f6c237c2118d387118
Owner decision: Required. See Decision needed.

Decision needed

  • Question: Should this PR ship output-only rotation with --skip-unreadable, GOG_KEYRING_NEW_PASSWORD, unlocked source reads, and the shared file-backend timeout exclusion?
  • Recommendation: Approve the documented workflow: Accept output-only rotation and its non-atomic snapshot limitation, explicitly approving the file-backend timeout exception and updating the architecture contract accordingly.
  • Why: The capability is new, the documented locking and timeout contract differs, and neither the discussion nor reviews contain owner approval; the contributor explicitly leaves this decision open.

Before merge

  • Resolve maintainer decision - Resolve the maintainer decision shown above before merge.

Findings

None.

Agent review details

How this fits together

The auth CLI resolves the selected file keyring, decrypts its entries, writes them through the existing encrypted-file serializer, and reports a verified output directory for deliberate installation.

flowchart TD
A[Auth rekey CLI] --> B[Backend and path checks]
B --> C[Read encrypted source entries]
C --> D[Decrypt with current password]
D --> E[Write separate encrypted output]
E --> F[Verify with new password]
F --> G[Report installation instructions]
Loading

Technical review

Best possible solution:

Ship an owner-approved output-only rotation workflow with an explicit concurrency contract and an agreed scope for the shared backend changes.

Do we have a high-confidence way to reproduce the issue?

This is a new capability rather than a bug report; current-main source confirms whole-keyring rotation is absent, and no target code was executed.

Is this the best way to solve the issue?

A separately verified encrypted copy protects the original credentials and preserves more than per-account export/import, while the concurrency and shared timeout choices need owner agreement.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning medium; reviewed against d48a86fb3fba.

Provenance checked

  • File-keyring encoding and enumeration keeps the original intent (8135cc3: Make key names safe on Windows while preserving legacy reads; the new output retains that encoding and omits internal bookkeeping.)
  • File-keyring read serialization changes intended behavior with a stated reason (f3d5753: Serialize credential reads and writes to avoid partial reads and concurrent mutations, as approved in Feature: add cross-process locking around keyring writes #597; rekey deliberately bypasses the normal opener to avoid modifying source bookkeeping.)
  • Keyring operation timeout changes intended behavior with a stated reason (6430dd1: Bound unresponsive keyring operations; the patch excludes actual file backends because timed-out goroutines can outlive the store lock.)

Testing

Proof path: shipped entry point.

Security

None.

Evidence

What I checked:

  • Current main lacks whole-keyring rotation: Main exposes keyring configuration and per-account token export/import, but no rekey command; token export does not preserve arbitrary keyring secrets. (internal/cmd/auth.go:110, d48a86fb3fba)
  • Verified introduced implementation: The pinned diff adds separate-output re-encryption, independent metadata and data verification, overlap guards, explicit output replacement, CLI integration, tests, and documentation. (internal/secrets/rekey.go:76, 0d18ccb2de8b)
  • Stable-release compatibility proof now supplied: The full PR body and contributor follow-up show a v0.45.0-created six-token keyring rotated and installed, preserved account metadata, successful Google calls, old-password rejection, rollback readability, and readability by v0.45.0 itself. Captured body SHA-256: b20ad568a204affb5c541969ae47afb7ff22b70ae3219a1750d7731fe8528e28. Follow-up: feat(auth): add gog auth rekey to rotate the file keyring password #1224 (comment). (0d18ccb2de8b)
  • Existing locking contract needs an owner decision: The architecture contract prohibits bypassing keyring locking and timeout behavior. In Feature: add cross-process locking around keyring writes #597, steipete approved serialized reads and writes and recorded concurrent-reader/writer proof. This PR deliberately reads without that lock and documents a non-atomic snapshot. (docs/spec.md:51, d48a86fb3fba)
  • Shared timeout behavior changes: Actual file backends stop receiving operation timeouts, including automatic file fallback. The patch explains that detached timeout workers can continue writing after the store lock is released. Earlier timeout policy and its rationale are recorded in feat(secrets): make keyring open timeout configurable, default 30s #845. (internal/secrets/backend.go:333, 0d18ccb2de8b)
  • Repository policy and prior finding checked: The full root AGENTS.md was applied; no nested AGENTS.md or maintainer-notes directory exists. The Unreleased entry now includes the required PR reference and contributor thanks. (CHANGELOG.md:5, 0d18ccb2de8b)

Likely related people:

  • Peter Steinberger: Raw commit 92abba7 adds internal/secrets/backend.go:326 relative to its recorded parents. This identifies author metadata, not feature responsibility or a PR merger. (role: source-line author; confidence: high; commits: 92abba72531b; files: internal/secrets/backend.go)
  • Malo Bourgon: Raw commit b3c2856 adds internal/secrets/backend.go:324 relative to its recorded parents. This identifies author metadata, not feature responsibility or a PR merger. (role: source-line author; confidence: medium; commits: b3c285613b74; files: internal/secrets/backend.go)

Review metrics

Metric Value Why it matters
Patch composition Production +694/-5; tests +1473; documentation +119/-2 Most added coverage exercises credential preservation, independent verification, path safety, interruption, and replacement failures.

Labels

Label changes:

  • add merge-risk: 🚨 compatibility: The PR introduces unlocked keyring snapshots and changes existing automatic file-backend operation-timeout behavior; those contract changes require owner agreement.
  • add proof: sufficient: Contributor real behavior proof is sufficient.
  • remove status: 📣 needs proof: Current PR status no longer selects a status label.

Label justifications:

  • P2: Useful credential-maintenance functionality with limited immediate impact and no established urgent regression.
  • merge-risk: 🚨 compatibility: The PR introduces unlocked keyring snapshots and changes existing automatic file-backend operation-timeout behavior; those contract changes require owner agreement.
  • rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🦞 diamond lobster and patch quality is 🐚 platinum hermit.
  • proof: sufficient: Contributor real behavior proof is sufficient.

Rating scale

6/6 🦀 challenger crab · 5/6 🦞 diamond lobster · 4/6 🐚 platinum hermit · 3/6 🦐 gold shrimp · 2/6 🦪 silver shellfish · 1/6 🧂 unranked krab. Overall follows the weaker of proof and patch quality; ✨ marks media proof (a screenshot, video, or linked artifact) that directly shows the changed behavior.

Workflow

ClawSweeper edits this one comment on every review. Comment @clawsweeper re-review for a fresh review only. Repair and merge execution lanes are retired.

History

Review history (1 earlier review cycle)
  • reviewed 2026-10-17T18:33:31.426Z sha 515fa21 :: needs real behavior proof before merge. :: [P3] Add the required changelog reference and contributor credit

Reviewed October 17, 2026, 2:51 PM ET / 18:51 UTC (Revision 2).

@sorenisanerd

sorenisanerd commented Oct 17, 2026 via email

Copy link
Copy Markdown
Contributor Author

@sorenisanerd
sorenisanerd force-pushed the feat/auth-keyring-rekey branch from 515fa21 to 0d18ccb Compare October 17, 2026 18:44
@sorenisanerd

Copy link
Copy Markdown
Contributor Author

@clawsweeper re-review

Addressed the changelog finding and both proof items at 0d18ccb2; the owner decision stays open.

  • Changelog reference and contributor credit (P3) — fixed in 0d18ccb2. The Unreleased entry now ends with (#1224) — thanks @sorenisanerd. per root AGENTS.md.
  • Real behavior proof and data-model compatibility — new ### Upgrade path from a keyring written by v0.45.0 section in the PR body. The keyring is written by the released v0.45.0 binary (auth tokens import of two real accounts into a fresh GOG_HOME: six token entries plus the .lock file it creates), read back with --check true and a real gmail labels list, then rotated by this branch and installed with the command it printed. After installation: identical accounts, service sets, client and grant timestamps; --check true and a real Gmail call succeed; the old password is rejected with aes.KeyUnwrap(): integrity check failed; the retained <keyring>.old opens with the old password and still authenticates; and v0.45.0 itself reads the rekeyed keyring, so rotation does not change the persisted format. The live keyring was never opened — its per-file digest was unchanged (b62d9c53…).
  • Owner decision (item 1) — still open. The question of whether to ship unlocked source reads, --skip-unreadable and GOG_KEYRING_NEW_PASSWORD is for a maintainer, not something the patch or this comment can settle.

@clawsweeper

clawsweeper Bot commented Oct 17, 2026 •

Copy link
Copy Markdown
Contributor

🦞👀
Exact review queued.

Re-review progress:

@clawsweeper clawsweeper Bot added merge-risk: 🚨 compatibility 🚨 Merging this PR could break existing users, config, migrations, defaults, or upgrades. proof: sufficient Contributor real behavior proof is sufficient. and removed status: 📣 needs proof The PR needs real behavior proof before ClawSweeper can clear the contributor ask. labels Oct 17, 2026
@sorenisanerd

Copy link
Copy Markdown
Contributor Author

The motivation, which I now realize I should have put front and center, was an accidental leak of my keyring password to an LLM, prompting (no pun intended) me to rotate said key. I could not find any existing tool to do this.

Add `gog auth rekey <outdir>`, which reads the file keyring with the current
password, re-encrypts every entry under a new password, and writes a verified
copy to the separate output directory. The live keyring is opened read-only
and left byte-identical, so no crash or bug in output writing can lose or
corrupt live credentials.

The output directory is a required positional argument, is created with the
keyring directory's permissions, and is refused when it is the keyring
directory, lies inside it, contains it, or is reached through a symlink or
case alias. A non-empty output is refused unless --force is passed, which
replaces those entries and reports exactly which were removed; a failed
replacement reports the removals that completed and names the entry that may
have been partially removed.

Before reporting success the command reopens the output with the new password
and reads every entry back, comparing data and metadata. It prints paths,
counts and key names only, never payloads or passwords, and prints the exact
installation command that retains the old directory until the new keyring is
proven. --skip-unreadable omits entries that cannot be decrypted and reports
their keys; an empty keyring reports that no password was changed.

Regenerate the command reference and document output-directory rotation in
Paths and State and the installation guide.

Validation: make ci gates (fmt-check, lint, deadcode, docs-check), the full
internal/secrets and internal/cmd suites, -race, and linux/darwin/windows
builds and test binaries. Every safety behaviour has a test that fails when
the behaviour is removed, confirmed by mutation testing.
@steipete
steipete force-pushed the feat/auth-keyring-rekey branch from 0d18ccb to 6ea0eb3 Compare October 20, 2026 17:58
@steipete
steipete merged commit e06131d into openclaw:main Oct 20, 2026
7 checks passed
@steipete

Copy link
Copy Markdown
Collaborator

Thanks @sorenisanerd — landed in e06131d.

The maintainer follow-up holds the source store lock throughout rekey, stages and independently verifies the complete output, fsyncs before atomic directory exchange on Linux/macOS, and rolls back publication failures. Existing output is refused on platforms without atomic exchange; Windows supports a fresh output path. Legacy formats and metadata are preserved, and the live credential files remain unchanged.

Validation: full make ci, focused rekey/CLI tests, race tests, and govulncheck ./... passed. No reachable vulnerability was found. Exact-head PR CI and merged-main CI are green. The Unreleased changelog includes contributor thanks, and the squash message preserves co-author credit. No release was performed.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

merge-risk: 🚨 compatibility 🚨 Merging this PR could break existing users, config, migrations, defaults, or upgrades. P2 Normal priority bug or improvement with limited blast radius. proof: sufficient Contributor real behavior proof is sufficient. rating: 🦐 gold shrimp Decent PR readiness signal, but merge confidence is limited.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants